/**
 * @file truth_table.h
 * @brief describes a truth table used for mapping input values to outputs
 * @author Scott Moyers
 * @date 2009
 */

/**
 * @page TruthTables Truth Tables
 *
 * @section AboutTruth About
 *
 * Truth tables define what your Genetic Algorithm is trying to synthesise.
 * Examples of truth tables can be found in ./truths/.
 *
 * @section FormatTruth Format
 *
 * Truth tables all start off with 2 numbers. The number of inputs and the number of outputs
 * e.g. for 4 inputs and 3 outputs it starts off:\n
 * 4 3
 * 
 * The following lines are the truth table. There should be 2^"numer of inputs" lines.
 * Truth tables currently only support 0's and 1's so no X's etc. Each line is the output
 * you desire for an incrementing binary input. e.g for a normal full adder the truth table would
 * be:\n
 * 000 00\n
 * 001 01\n
 * 010 01\n
 * 011 10\n
 * 100 01\n
 * 101 10\n
 * 110 10\n
 * 111 11\n
 *
 * In our truth table format the incrementing binary input is implicit so only the second column
 * is included.
 *
 * The entire full adder truth table file can be seen in ./truths/fulladder.truth but
 * is also included below:\n
 * 3 2\n
 * 00\n
 * 01\n
 * 01\n
 * 10\n
 * 01\n
 * 10\n
 * 10\n
 * 11\n
 *
 * @section UsingTruth Using Truth Tables
 *
 * Truth Tables can be added into configuration files using:\n
 * truthtable filename.truth
 */

#ifndef MY_TRUTH_TABLE_H
#define MY_TRUTH_TABLE_H

#include <stdio.h>
#include "dSFMT.h"

/**
 * @brief A boolean truth table mapping input values to outputs
 */
struct TruthTable {
	unsigned int **signals; /**< array of signals */
	unsigned int nins;      /**< number of inputs to the truth table */
	unsigned int nouts;     /**< number of outputs for the truth table */
};

/**
 * function for creating a new truth table
 * @param inputs the number of boolean inputs in the truth table
 * @param outputs the number of boolean outputs in the truth table
 * @return a pointer to the new truth table
 */
struct TruthTable *new_truth_table(unsigned int inputs, unsigned int outputs);

/**
 * function to create a new truth table from a file
 * @param f path to the truth table file
 * @return a new truth table specifieced by the input file
 */
struct TruthTable *new_truth_table_from_file(const char *f);

/**
 * function for deleting a truth table
 * @param table the truth table to delete
 */
void free_truth_table(struct TruthTable * table);

/**
 * prints a truth table to file
 * @param fp the file pointer
 * @param table the truth table to print out
 */
void print_truth_table(FILE * fp, struct TruthTable * table);

/**
 * creates a new random truth table
 * @param dsfmt the random number generator
 * @param inputs the number of inputs
 * @param outputs number of outputs
 * @return a pointer to the new random truth table
 */
struct TruthTable *new_rand_truth_table(dsfmt_t *dsfmt, unsigned int inputs, unsigned int outputs);

/**
 * return a new copy of the input truth table
 * @param t truth table to copy
 * @return new copied truth table
 */
struct TruthTable *copy_truth_table(struct TruthTable *t);


#endif
